---
title: Checkbox
description: Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/Checkbox.html
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/inputs/checkbox.mdx?plain=1
---

<ComponentPreview
  name="checkbox/demos/default"
  preview={`<Checkbox>I accept the <Link href="/terms">terms and conditions</Link></Checkbox>`}
/>

## Installation

```package-install
npx shadcn@latest add @dotui/checkbox
```

## Usage

Use `Checkbox` to allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

```tsx
import { Checkbox } from "@/components/core/checkbox";

<Checkbox>I accept the terms and conditions</Checkbox>;
```

```tsx
import { CheckboxIndicator, CheckboxRoot } from "@/components/core/checkbox";

<CheckboxRoot>
  <span>I accept the terms and conditions</span>
  <CheckboxIndicator />
</CheckboxRoot>;
```

## Options

### Variants

Use the `variant` prop to control the visual style of the checkbox.

<ComponentPreview
  name="checkbox/demos/variants"
  preview={`<Checkbox variant="card">I accept the terms and conditions</Checkbox>`}
/>

### Appearance

You can make the checkbox appear as a card using the `appearance` prop.

<ComponentPreview
  name="checkbox/demos/card"
  preview={`<Checkbox variant="card">I accept the terms and conditions</Checkbox>`}
/>

### Indeterminate

A checkbox can be in an indeterminate state, controlled using the `isIndeterminate` prop.

<ComponentPreview
  name="checkbox/demos/indeterminate"
  preview={`<Checkbox isIndeterminate>Select all</Checkbox>`}
/>

### Disabled

Use the `isDisabled` prop to disable the checkbox.

<ComponentPreview
  name="checkbox/demos/disabled"
  preview={`<Checkbox isDisabled>I accept the terms and conditions</Checkbox>`}
/>

### Read only

The `isReadOnly` prop makes the selection immutable. Unlike isDisabled, the Checkbox remains focusable.

<ComponentPreview
  name="checkbox/demos/read-only"
  preview={`<Checkbox isReadOnly>I accept the terms and conditions</Checkbox>`}
/>

## Composition

If you need to customize things further, you can drop down to the composition level.

<ComponentPreview
  name="checkbox/demos/composition"
  preview={`<CheckboxRoot className="..">
    <span>I agree to the terms and conditions</span>
    <CheckboxIndicator className=".."/>
  </CheckboxRoot>`}
/>

## Uncontrolled

The `defaultSelected` prop can be used to set the default state.

<ComponentPreview
  name="checkbox/demos/uncontrolled"
  preview={`<Checkbox defaultSelected>I accept the terms and conditions</Checkbox>`}
/>

## Controlled

Use the `isSelected` and `onChange` props to control the value of the input.

<ComponentPreview
  name="checkbox/demos/controlled"
  preview={`const [checked, setChecked] = React.useState(false);
  return (
    <Checkbox isSelected={checked} onChange={setChecked}>
      I accept the terms and conditions
    </Checkbox>
  );`}
/>

## API Reference

| Prop                 | Type                                                                                                  | Default     | Description                                                                                                                                                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variant`            | `"default" \| "card"`                                                                                 | `"default"` | The visual style of the checkbox group.                                                                                                                                                                                               |
| `inputRef`           | `MutableRefObject<HTMLInputElement>`                                                                  | -           | A ref for the HTML input element.                                                                                                                                                                                                     |
| `isIndeterminate`    | `boolean`                                                                                             | -           | Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.                                                                                                                 |
| `defaultSelected`    | `boolean`                                                                                             | -           | Whether the element should be selected (uncontrolled).                                                                                                                                                                                |
| `isSelected`         | `boolean`                                                                                             | -           | Whether the element should be selected (controlled).                                                                                                                                                                                  |
| `value`              | `string`                                                                                              | -           | The value of the input element, used when submitting an HTML form.                                                                                                                                                                    |
| `isDisabled`         | `boolean`                                                                                             | -           | Whether the input is disabled.                                                                                                                                                                                                        |
| `isReadOnly`         | `boolean`                                                                                             | -           | Whether the input can be selected but not changed by the user.                                                                                                                                                                        |
| `isRequired`         | `boolean`                                                                                             | -           | Whether user input is required on the input before form submission.                                                                                                                                                                   |
| `isInvalid`          | `boolean`                                                                                             | -           | Whether the input value is invalid.                                                                                                                                                                                                   |
| `validate`           | `(value: boolean) => ValidationError\| true\| null\| undefined`                                       | -           | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead. |
| `autoFocus`          | `boolean`                                                                                             | -           | Whether the element should receive focus on render.                                                                                                                                                                                   |
| `name`               | `string`                                                                                              | -           | The name of the input element, used when submitting an HTML                                                                                                                                                                           |
| `validationBehavior` | `'native' \| 'aria'`                                                                                  | `'native'`  | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.                                                                        |
| `children`           | `ReactNode \| (values: CheckboxRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | -           | The children of the component. A function may be provided to alter the children based on component state.                                                                                                                             |
| `className`          | `string`                                                                                              | -           | The CSS className for the element.                                                                                                                                                                                                    |
| `style`              | `CSSProperties \| (values: CheckboxRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -           | The inline style for the element. A function may be provided to compute the style based on component state.                                                                                                                           |

| Event           | Type                              | Description                                                        |
| --------------- | --------------------------------- | ------------------------------------------------------------------ |
| `onChange`      | `(isSelected: boolean) => void`   | Handler that is called when the element's selection state changes. |
| `onFocus`       | `(e: FocusEvent<Target>) => void` | Handler that is called when the element receives focus.            |
| `onBlur`        | `(e: FocusEvent<Target>) => void` | Handler that is called when the element loses focus.               |
| `onFocusChange` | `(isFocused: boolean) => void`    | Handler that is called when the element's focus status changes.    |
| `onKeyDown`     | `(e: KeyboardEvent) => void`      | Handler that is called when a key is pressed.                      |
| `onKeyUp`       | `(e: KeyboardEvent) => void`      | Handler that is called when a key is released.                     |
| `onHoverStart`  | `(e: HoverEvent) => void`         | Handler that is called when a hover interaction starts.            |
| `onHoverEnd`    | `(e: HoverEvent) => void`         | Handler that is called when a hover interaction ends.              |
| `onHoverChange` | `(isHovering: boolean) => void`   | Handler that is called when the hover state changes.               |

| Data attribute         | Description                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| `[data-selected]`      | Whether the checkbox is selected.                                |
| `[data-indeterminate]` | Whether the checkbox is indeterminate.                           |
| `[data-hovered]`       | Whether the checkbox is currently hovered with a mouse.          |
| `[data-pressed]`       | Whether the checkbox is currently in a pressed state.            |
| `[data-focused]`       | Whether the checkbox is focused, either via a mouse or keyboard. |
| `[data-focus-visible]` | Whether the checkbox is keyboard focused.                        |
| `[data-disabled]`      | Whether the checkbox is disabled.                                |
| `[data-readonly]`      | Whether the checkbox is read only.                               |
| `[data-invalid]`       | Whether the checkbox invalid.                                    |
| `[data-required]`      | Whether the checkbox is required.                                |

## Accessibility

### Keyboard interactions

| Key     | Description                                            |
| ------- | ------------------------------------------------------ |
| `Space` | Toggles the checkbox between selected and not selected |
